---
title: 'Migrating between major versions'
description: 'Learn how to migrate between major versions of the Schedule-X calendar'
---

# Migrating between major versions

## Premium v13 to v14

With v14 of the premium plugins, there were a couple of minor breaking changes to the API:

- `ResourceViewConfig.highlightToday` now defaults to true, meaning the current day is highlighted by default in resource view. To keep old behaviour, set it to false.
- `ResourceViewConfig.dayNameFormat` now defaults to 'short'. This will display day names in the daily view. To keep old behaviour, set it to false.

## Migration from v2 to v3

With v3 of the Schedule-X calendar, there were a few breaking changes to the API, especially:

- `start` and `end` properties of events now expect Temporal.ZonedDateTime or Temporal.PlainDate instances, rather than strings.
- `selectedDate` of the calendar config now expects a `Temporal.PlainDate` instance, rather than a string.
- `minDate` and `maxDate` of the calendar config now expect `Temporal.PlainDate` instances, rather than strings.
- Callbacks that used to accept a date parameter of format `YYYY-MM-DD` now use instances of `Temporal.PlainDate` instead.
- Callbacks that used to accept a date-time parameter of format `YYYY-MM-DD HH:MM` now use instances of `Temporal.ZonedDateTime` instead.

Additionally, there were some other breaking changes to the UI and plugins ecosystem:

- v3 of the open source packages, now work together with v13 of the premium plugins. There was a jump from premium v3 -> v13, to make it abundantly clear that there is no numeric correlation between the open source major version and the premium major version.
- `ResourceViewConfig.onLazyLoadDate` and `ResourceViewConfig.onLazyLoadMonth` for @sx-premium/resource-scheduler now expect `Temporal.PlainDate` instances, rather than strings.
- Time grid events (in day- and week views), now reactively display title and time inline, if there is no vertical space to display them in two lines.
- The view select element now features a chevron icon, to indicate that it is a dropdown.
- The iCalendar plugin returned in v3.4 with Temporal support, but it assumes all timestamps are UTC. Keep the calendar timezone at `UTC` to preserve the legacy behaviour or pre-process the events if you need timezone-aware rendering.

The docs for v2 can still be found at https://v2.schedule-x.dev

## Migration from @sx-premium v2 to v3

v3 of the premium plugins brought some breaking changes to the interactive event modal plugin, and nothing else. If
you do not use this, you should be able to update to v3 without changing anything.

### Breaking changes in the interactive event modal

#### 1. Event recurrence UI and API
The event recurrence section now has more options. Users can set an interval for the recurrence, decide on which
weekdays the event should recur, and decide between `until`, `count` or infinite, for limiting the recurrence.

Previously, you could configure the rrule fields like this:

```ts
const modal = createInteractiveEventModal({
  fields: {
    rruleFrequency: {},
    rruleUntil: {}
  }

  // other config
})
```

In v3, this will throw an error, since you need to either configure all rrule fields, or none. Now you can do this:

```ts
const modal = createInteractiveEventModal({
  fields: {
    // your other fields
    ...rruleFields()
  }

  // other config
})
```

#### 2. `onAddEvent` callback

The `onAddEvent` callback is now required in the modal configuration. If you do not provide it, the modal will throw an error.


## Migration guide for v2

V2 brought a few breaking changes in the UI and internal APIs.

If you haven't built your own custom plugins, you will probably be able to migrate effortlessly.

### Migrating with custom plugins

If you have built custom plugins that use the internal config in some way, you will need to change the
way you access the config values. This is because the config values are now mostly reactive. So for example:

v1.x.x: `$app.config.locale` ➡️ v2.x.x: `$app.config.locale.value`

And this pattern repeats itself across the different config values.

Also, the `init` function on plugins has been renamed into `onRender`, to better reflect when it is invoked. It is
now accompanied by another method for plugins, `beforeRender`.

### Breaking changes in the UI

The UI had a few breaking changes:
- The time grid event now displays a location by default, if one exists on the event. The `showLocation` option has
now been removed.
- Month grid- and date grid events now display a timestamp next to their title, for all timed events.
- The view selection component is now hidden, if there is only one view available.

### Premium plugins

If you are using the premium plugins, you will also need to migrate them to at least v2, but preferably even to v3.

## `@schedule-x/react`

The `Calendar` alias for the `ScheduleXCalendar` component has been removed. If you were using this API, use `ScheduleXCalendar` instead.

